Skip to content

config: safer handling of the encrypted key file (atomic re-encryption, clear errors; format unchanged) - #170

Merged
EnzinoBB merged 8 commits into
masterfrom
fix/node-key-salt
Nov 4, 2026
Merged

EnzinoBB merged 8 commits into
masterfrom
fix/node-key-salt

Conversation

@EnzinoBB

@EnzinoBB EnzinoBB commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

What

Safer handling of the encrypted key file: atomic re-encryption, no empty file on failure, and clear errors. The file format is unchanged and stays compatible with the official node. The node writes and reads only the 88-byte format of cscrypto's PrivateKey::getEncrypted / readFromEncrypted. (Earlier commits on this branch added a second format; it has been removed entirely. Nothing writes it or reads it.)

  • Atomic re-encryption (--encryptkey, the change of password offered at start, a new key at first start, and --dumpkeys):
    • The node writes NodePrivate.txt.tmp (mode 0600, O_NOFOLLOW), fsyncs it, renames it over the key file (a symlink is followed and its target replaced), then fsyncs the folder.
    • On Windows: CreateFile, FlushFileBuffers, MoveFileEx(REPLACE_EXISTING | WRITE_THROUGH).
    • Every return value is checked. On failure the previous file stays and an error is logged instead of the success line.
  • No empty key file: a failed encryption is an error. Before this change, an empty buffer was written.
  • Clear errors:
    • A decoded length other than 64 or 88 stops the node once, before any prompt, with Bad private key file in ... (N bytes). Before this change, the node asked for a password, and a longer file crashed it.
    • A failed key derivation (the 1 GiB Argon2id) is an error instead of a null dereference. client/config/keyfilecrypt.{hpp,cpp} implements cscrypto's format byte for byte (same salt, derivation, cipher and layout) with these checks.
    • The KDF identifiers are pinned (crypto_pwhash_ALG_ARGON2ID13, argon2id OPSLIMIT/MEMLIMIT_SENSITIVE) to the same values as before.
  • Password file: a file used as password is read directly into its buffer and sodium_memzero'ed after use.
  • cscrypto is not changed (no gitlink changes).
  • Docs: a CHANGES row, a differences.md entry, and a README line advising a long, unique password when the key is encrypted.

Byte compatibility (proof)

  • Unit tests (keyfilecrypt_tests, their own ctest entry):
    • a file written by cscrypto opens, and re-encrypting its key with the same password and nonce gives the same bytes and the same base58 text;
    • cscrypto's reader (the official node's code) opens what this node writes;
    • this node opens what cscrypto writes;
    • wrong password, a changed byte, other lengths (including 104) and a failed derivation are all refused.
  • All 4 cscrypto-written vectors of CreditsCommunity/wallet re-encrypt byte-identically with this code, and cscrypto's reader opens the result.
  • By hand, on scratch folders, with the console answered on stdin:
    • this node --encryptkey writes 88 bytes, which the official node (a build of 4a95aaa whose key code is unchanged), the previous community node and this node all open; the official node refuses a wrong password, and the file stays byte-for-byte unchanged;
    • an 88-byte file written by the official node opens with this node;
    • so does one written by the previous community node;
    • a 104-byte file stops this node with Bad private key file ... (104 bytes);
    • a read-only folder gives "Could not write ...: the key file was left as it was", with the plain key intact;
    • --encryptkey through a symlink replaces the target.

Consensus

None. Only the local key file is affected.

🤖 Generated with Claude Code

EnzinoBB and others added 4 commits November 4, 2026 17:44
A new encryption of NodePrivate.txt (--encryptkey, "[1] Encrypt with password" at the first
start, the change of password at start) now writes base58(salt (16 random bytes) || nonce
(8 random bytes) || crypto_aead_chacha20poly1305 ciphertext and tag (80 bytes)), 104 bytes
decoded. The key is crypto_pwhash with the same parameters as before (Argon2id,
OPSLIMIT_SENSITIVE, MEMLIMIT_SENSITIVE) and the file's own salt. The salt and nonce come from
randombytes_buf; no associated data: the format is told by its length.

Reading tells the formats apart by the decoded length: 88 bytes is the format of older
versions, opened by cscrypto's PrivateKey::readFromEncrypted as before and never rewritten;
104 is the new one; any other length does not open (64 is a plain key, unchanged). Prompts,
retries and the file-as-password mode are unchanged. The code lives in the node
(client/config/keyfilecrypt.cpp), so the cscrypto submodule is not changed.

A failed encryption (e.g. Argon2id unable to allocate its memory) now returns an error instead
of an empty buffer, so the key file is never overwritten with an empty line.

Only the local key file is concerned: nothing on the wire, in storage or in consensus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…vations

Each derivation is Argon2id with 1 GiB (about 5 s here): the tests share their encryptions and
run as keyfilecrypt_tests, so nodetests keeps its time within the per-test timeout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EnzinoBB and others added 4 commits November 4, 2026 20:04
…de (review M1, L1-L5)

- M1: the key file is written to NAME.tmp (0600, O_NOFOLLOW), fsync'ed, renamed over NAME (a
  link is followed, its target replaced) and the folder fsync'ed; on Windows CreateFile,
  FlushFileBuffers and MoveFileEx(REPLACE_EXISTING | WRITE_THROUGH). Every return value is
  checked: on failure the old file stays and an error is logged instead of the success line
  (re-encryption, --encryptkey, a new key at first start, --dumpkeys).
- L1: crypto_pwhash_ALG_ARGON2ID13 with the argon2id OPSLIMIT/MEMLIMIT_SENSITIVE, the values the
  generic aliases had: no format change.
- L2: a decoded length other than 64, 88 or 104 stops once with "Bad private key file in ...
  (N bytes)" before any prompt.
- L3: the legacy format is read in keyfilecrypt.cpp with the same derivation and cipher, the key
  allocation and the derivation checked, so a failed derivation is an error instead of a null
  dereference in cscrypto's reader; legacy files are still never rewritten.
- L4: a file used as password is read straight into its buffer and wiped after use.
- L5: tests for a changed ciphertext byte of a 104-byte file and for a failed derivation (both
  directions: empty encryption, no key, no crash).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…check

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The key file format is unchanged: the node writes and reads only the 88-byte format of
cscrypto's PrivateKey::getEncrypted / readFromEncrypted, which the official node and every
earlier node write and read. The 104-byte format of the previous commits is removed: never
written, never read (a 104-byte file now stops the node like any other unexpected length).

cs::keyfile::encrypt / decrypt implement that same format (same salt, same Argon2id derivation
with pinned identifiers of the same values, same cipher and layout) so that a failed allocation
or derivation is an error instead of a null dereference; encryptWithNonce lets the tests prove
the bytes identical to cscrypto's.

Kept from the review: atomic re-encryption (tmp, fsync, rename, every return value checked, no
false success line), no empty key file when encryption fails, "Bad private key file in ...
(N bytes)" for a length other than 64 or 88 before any prompt, the file-as-password buffer
wiped.

Tests: a cscrypto-written file opens and re-encrypts with its nonce to the same bytes; cscrypto's
reader opens what this node writes and this node opens what cscrypto writes; wrong password,
changed byte, other lengths (104 included), failed derivation.

Docs: CHANGES and differences describe safer handling with the format unchanged; README advises
a long, unique password when the key is encrypted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB EnzinoBB changed the title config: the key file encryption uses a random salt per file config: safer handling of the encrypted key file (atomic re-encryption, clear errors; format unchanged) Nov 4, 2026
EnzinoBB added a commit to CreditsCommunity/wallet that referenced this pull request Nov 4, 2026
…t-only

The node keeps its encrypted key file format (CreditsCommunity/node#170 no longer adds one):
DecryptNodeKey opens the 88-byte format only, as on main; the salted vectors, the
encrypt-legacy tool command, the e2e's 104-byte case and the doc changes about two formats are
reverted to main.

Kept (review L6): the node-format encryptor is out of the production API, in
internal/keys/keystest (the 88-byte format; it does not import keys, so keys' own tests use it
and check keystest.Seal byte-exact against the node's vectors).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@EnzinoBB
EnzinoBB merged commit 4d79c9b into master Nov 4, 2026
3 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant